All Databases Inside Mac - AppleEvents

Getting Data Out of a Parameter

You can use the AEGetParamPtr or AEGetParamDesc function to get the

data out of a parameter. Use the AEGetParamPtr function to return the data

contained in a parameter. Use the AEGetParamDesc function when you need

to get the descriptor record of a parameter. You often use the

AEGetParamDesc function to extract the descriptor list from a parameter.

You can also use the AEGetKeyPtr function to return the data contained in a

parameter. The AEGetKeyPtr function provides an additional feature-you can

use this function to get data out of an AE record.

For example, you use an Apple Event Manager function to get the data out

of a Section Read event. The Edition Manager sends your application a

Section Read event to tell your application to read updated information from

an edition into the specified subscriber. The direct parameter of the Apple

event contains a handle to the section record of the subscriber. You can use the

AEGetParamPtr function to get the data out of the Apple event.

You specify the Apple event that contains the desired parameter, the keyword

of the desired parameter, the descriptor type the function should use to return

the data, a buffer to store the data, and the size of this buffer as parameters to

the AEGetParamPtr function. The AEGetParamPtr function returns the

descriptor type of the resulting data and the actual size of the data, and it

places the requested data in the specified buffer.

SectionHandle sectionH;

AppleEvent theAppleEvent;

DescType returnedType;

Size actualSize;

OSErr myErr;

myErr = AEGetParamPtr(& theAppleEvent, keyDirectObject, typeSectionH,

& returnedType, (Ptr) & sectionH, sizeof( sectionH),

& actualSize);

In this example, the keyDirectObject keyword specifies that the

AEGetParamPtr function should extract information from the direct

parameter; AEGetParamPtr returns the data in the buffer specified by the

sectionH variable.

You can request that the Apple Event Manager return the data using the

descriptor type of the original data or you can request that the

Apple Event Manager coerce the data into a descriptor type that is

different from the original. See Built-in Coercion Handlers for a list of

coercions that the Apple Event Manager can perform. You can specify the

desired descriptor type as typeWildCard if you don't want any coercion

performed-in which case, the AEGetParamPtr function returns the original

descriptor type of the parameter.

The typeSectionH descriptor type specifies that the returned data should be

coerced to a handle to a section record. You can use the information returned in

the sectionH variable to identify the subscriber and read in the information

from the edition.

In this example, the AEGetParamPtr function returns in the returnedType

variable the descriptor type of the resulting data. In most cases, the

descriptor type of the resulting data matches the requested

descriptor type, unless the Apple Event Manager wasn't able to coerce the

data to the specified descriptor type. If the coercion fails,

the Apple Event Manager returns the result code.

The AEGetParamPtr function returns the actual size of the data in the

actualSize variable. If the value returned in the actualSize variable is greater

than the amount your application allocated for the buffer to hold the returned

data, your application can increase the size of its buffer to this amount, and get

the data again. You can also choose to use the AEGetParamDesc function when

your application doesn't know the size of the data.

You can use the AEGetParamDesc function to return the descriptor record

of a parameter. This function is useful, for example, when extracting

descriptor lists from a parameter.

You specify the Apple event that contains the desired parameter, the keyword

of the desired parameter, the descriptor type the function should use to return

the descriptor record, and a buffer to store the returned

descriptor record as parameters to the AEGetParamDesc function. The

AEGetParamDesc function returns the descriptor record using the specified

descriptor type.

For example, the direct parameter of the Open Documents event contains a

descriptor list that specifies the documents to open. You can use the

AEGetParamDesc function to get the descriptor list out of the direct

parameter.

AEDescList docList;

AppleEvent theAppleEvent;

OSErr myErr;

myErr = AEGetParamDesc(& theAppleEvent, keyDirectObject, typeAEList,

& docList);

In this example, the Apple event specified by the variable the AppleEvent

contains the desired parameter. The keyDirectObject keyword specifies that

the AEGetParamDesc function should get the descriptor record of the direct

parameter. The typeAEList descriptor type specifies that the descriptor record

should be returned as a descriptor list. In this example, the

AEGetParamDesc function returns a descriptor list in the docList variable.

The descriptor list contains a list of descriptor records. To get the

descriptor records and their data out of a descriptor list, use the

AECountItems function to find the number of descriptor records in the list,

and then make repetitive calls to the AEGetNthPtr function to get the data out

of each descriptor record.

Note that the AEGetParamDesc function copies the descriptor record from

the parameter. When you're done with a descriptor record that you obtained

from AEGetParamDesc, you must dispose of it by calling the

AEDisposeDesc function.

Referenced by (10):